<HTML><HEAD><TITLE>set_event_handler(+EventId, ++PredSpec)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Event Handling</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>set_event_handler(+EventId, ++PredSpec)</H1>
Set an event handler PredSpec for the event EventId.


<DL>
<DT><EM>EventId</EM></DT>
<DD>Atom or Integer.
</DD>
<DT><EM>PredSpec</EM></DT>
<DD>Term of the form Atom/Integer, or defers(Atom/Integer).
</DD>
</DL>
<H2>Description</H2>
   Assigns the procedure specified by PredSpec as the event handler
   for the event specified by EventId.  The event name can be either
   an arbitrary atom or a valid error number (as returned by
   current_error/1).

<P>
   An event handler which is used as an error handler can have 4
   optional arguments:
   <UL>
       <LI>the 1st argument is the event number/identifier itself
       <LI>the 2nd argument is the culprit (a structure corresponding to
	   the call which caused it)
       <LI>the 3rd argument is the context module (or the lookup module
       	   if the context module is unknown)
       <LI>the 4th argument is the lookup module for the call
   </UL>
   The error handler is free to use less than 4 arguments.
   </UL>

<P>
   Handlers for events raised by event/1 or posted to the system from
   the outside usually have no arguments or just the event name.

<P>
   Events can be raised by
<PRE>
   - one of the builtins event/1, error/2 or error/3.
   - posting an event from external code using ec_post_event().
   - an interrupt whose handler has been specified as event/1.
</PRE>
   The latter two have the effect of dynamically inserting an event/1
   goal into the current execution at the next synchronous point,
   which is usually just before the next predicate call.

<P>
   If the handler is specified as defers(Name/Arity), then the event has
   the defer-property. This means that event handling is automatically
   deferred on entering the event's handler, thus preventing other events
   from interrupting the handler. Such handlers must always explicitly invoke
   events_nodefer/0 before exiting in order to reenable event handling.
<P>

<H3>Modes and Determinism</H3><UL>
<LI>set_event_handler(+, ++) is det
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Either EventId or PredSpec is not instantiated.
<DT><EM>(5) type error </EM>
<DD>EventId is neither atom nor integer.
<DT><EM>(5) type error </EM>
<DD>PredSpec is not of the form Atom/Integer or defers(Atom/Integer).
<DT><EM>(6) out of range </EM>
<DD>EventId is integer, but not a valid error number.
<DT><EM>(6) out of range </EM>
<DD>PredSpec specifies an illegal handler arity.
</DL>
<H2>Examples</H2>
<PRE>
Success:
    ?- event(hello).
    warning: no handler for event in hello
    yes.

    ?- set_event_handler(hello, writeln/1).    
    yes.

    ?- event(hello).
    hello
    yes.
</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/event/current_error-1.html">current_error / 1</A>, <A HREF="../../kernel/event/get_event_handler-3.html">get_event_handler / 3</A>, <A HREF="../../kernel/event/error-2.html">error / 2</A>, <A HREF="../../kernel/event/error-3.html">error / 3</A>, <A HREF="../../kernel/event/event-1.html">event / 1</A>, <A HREF="../../kernel/event/reset_event_handler-1.html">reset_event_handler / 1</A>, <A HREF="../../kernel/event/events_nodefer-0.html">events_nodefer / 0</A>
</BODY></HTML>
